SMath Studio desktop provides the possibility to write plug-ins to extend program's features. The simplest feature you can think to add in the program is probably a function, and this is what we will do step-by-step in this tutorial.

First of all, we have to decide our goal. In this plug-in, we will try to create a combinations function that achieves what is shown below:

The finished function syntax will be in the form:

This tutorial as well as the complete plug-in code can be found in the public SVN repository of SMath Studio:

 

To accomplish our task we need an IDE (Integrated Development Environment); you can use the one you want, in this example we will use Visual Studio Community 2015 (you can download it for free on the official website https://www.visualstudio.com/vs/)

The second requirement is to have SMath Studio on your system.

 

1. Once Visual Studio is installed, open it and click on File ⇒ New Project from the main menu or Start ⇒ New Project from the Start Page

 

 

Be sure to save your project periodically as you work on this tutorial!

 

2. In the New Project dialog, choose .NET Framework 2.0, then navigate to Templates ⇒ Other Languages ⇒ Visual Basic ⇒ Windows ⇒ Class Library and type the name for this project.

In this case, we choose CombinFunction. Once all is done, click on OK.

3. Now make the Solution Explorer visible (if it is not visible already) by clicking on View ⇒ Solution Explorer

4. In the Solution Explorer, right-click the project name and click Unload Project.

5. Now will see CombinFunction (unavailable). Right-click on it and choose Edit CombinFunction.vbproj.

6. The project file will be opened. Scroll down to the first <ItemGroup> tag and add the following code above it:

These lines of code will allow you to have a plug-in ready to be shared with the community, and they let you to

compile the plug-in in Debug mode on your machine. If is not in your purposes to share the plugin, you can even use the code below instead.

"C:\Program Files (x86)\SMath Studio" is obviously the path of SMath Studio on your system (you have to change it if is different).

Under the previous code, add the following code:

This will ensure that the most recent APIs of SMath Studio available on your system will be loaded once you open and compile the project.

Once done, you should see something like in this screenshot. The yellow vertical bar shows the lines of code where there are changes respect to the last save; color becomes olive green after saving to show lines edited since the begin of the session.

7. Save it, then go back to Solution Explorer window, right-click on the project name and then on Reload Project.

Confirm on the dialog that ask you if you to close all the files, if it is prompted.

If all is gone right, you will see that now the SMath Studio assemblies are loaded in your project (in the Solution Explorer expand the References item)

Now everything is ready to start coding!

8. In the Solution Explorer double-click on Class1.vb

9. In the editing window, above the class definition, type in the following:

10. Within the class definition type the following:

then press enter; this will automatically insert an interface (with the interface members) that must be implemented in the class (see endnote 1). You can even click on the light bulb and choose

"Implement interface"

11. Next, type in the following:

12. Then scroll down the page and find the following subroutine:

Replace the exception code with this:

This is required in any plug-in made for SMath Studio.

- The 2nd argument represents the version number of Smath for which you are developing this plug-in. So if you are developing for SMath version 0.98, you insert 98. However, if the version you are targeting is different, enter the appropriate number.

- The 3rd argument will be the same for any plug-in, never change it!

13. Now scroll the code to the following subroutine:

type in the following within the Get block (see endnote 2):

14. Now scroll the code to the following function:

This allows SMath Studio (and the user) to know several things about your function:

- The 1st argument, "combin", is the function name to use inside the worksheets;

- The 2nd argument, TermType.Function, is the type of object combin; we'll see it again later;

- The 3rd argument, "(n, k) - Returns...", is the description available in the dynamic assistance;

- The 4th argument, FunctionSections.Unknown, is used to group functions by categories (CTRL+E in SS);

- The 5th argument, true, is to display the function in the dynamic assistance (use false to hide it).

15. Now scroll to the top and add another interface:

to do it, add a comma after the first interface and type the new one, then implement his members (hit return)

16. If you scroll down the code, another function is now available:

type in the following conditional If statement:

 

that means "if what is being processing is my function, then do something"

17. Now type in the following within the If block:

These preprocessing steps are needed to correctly prepare the arguments. This means that all possible substitutions will be performed.

18. Next, type the following:

This will prepare a container for the answer, made by Terms; these are the low-level units to build math from within the plug-ins. To create the answer, we have to compose an expression array formed in Reverse Polish Notation (see endnote 3). The mathematical expression is:

it can be expressed in RPN as:

n ! k ! n k ‐ ! * /

Thus, type in the following lines to compose the list of terms in RPN:

19. To finish up the function, type the following right below our List:

This will returns the result and that the function we were looking for is found.

A result is needed even to know if this is not the plug-in that handle the function in evaluation:

20. The math is done. Now we have to check if the setup of the plug-in is complete; go in the Solution Explorer and select Show All Files (if not yet selected).

Navigate to My Project ⇒ AssemblyInfo.vb, double-click on this file.

21. Now we can edit some attributes (adjust with your owns):

22. There should be a Guid attribute; if not, you must add it. Every plug-in must have a different one.

It is the identifier of your plug-in, and it is used to save the dependency when you use combin() in a worksheet. Remember: there are many like it, but this one is mine.

If it is missing, you can find one guid in the project file (see point 4 above)

23. Last thing here is the version. Add an asterisk for the build and revision numbers of the AssemblyVersion, so you will have always a new progressive version every time you will compile the plug-in. AssemblyFileVersion, if available, can be safely removed (otherwise you have to update it manually).

24. Before testing, we have to open again the project file, as shown in point 4. Once done, go above the </Project> closing tag in the last line and paste the following:

This makes possible to deploy automatically all the build files in the proper directory.

for SMath Studio installed

for SMath Studio portable

Save it, then go back to Solution Explorer window, right-click on the project name and then on Reload Project.

Confirm on the dialog that ask you if you to close all the files, if it is prompted.

25. Time to test! In the Solution Explorer, right-click the solution name and click on Rebuild.

26. Now run SMath Studio, then click on Tools ⇒ Plugins...

In the Quick search field, we search for combin; we'll see that our plugin is loaded and enabled!

27. Is our function loaded? Go to Insert ⇒ Function... or click the Function symbol on the Toolbar.

In the Function's name list, type c and scroll down to find our combin function; the description is the one we have defined at point 12. Since at that point we haven't provided the number of the arguments, it is shown with three points (undefined number of arguments) but only if we will 2 arguments the function will works (because we have defined this behavior at point 16).

If you type combin on the canvas (with Dynamic assistance enabled):

Press TAB and test it. If the result is like in the screenshot below, you have successfully created your first plug-in!

If you go back at point 14, we can use this to force a 2 arguments function on TAB key press

Once applied, both the number and the type of arguments are shown to the user, and TAB will provide a 2 arguments function.

28. However, in the real world, we seldom get by without making mistakes from time-to-time. Let’s now show how to debug our plug-in. Typically, you would debug your application before doing steps 24 through 27 that were outlined above. Debugging an application add‐in with Visual Studio Community is easy.

On the Visual Studio toolbar, cllick on the drop-down aof the Run button:

In the "Run external program" add "C:\Program Files (x86)\SMath Studio\Solver.exe" (without quotes) or the actual location on your PC.

Save it, then go back to your code.

31. Within Visual Basic, set a breakpoint at a convenient location. Simply place your cursor in the line at which you wish to set the breakpoint and click on Debug ⇒ Toggle Breakpoint as shown below:

A big red dot will show that the breakpoint is set on the choosen line (the if statement of our function):

32. Start debugging. Click on Debug ⇒ Start Debugging or Start on the Visual Studio toolbar.

When you do this, Visual Studio will automatically start up Smath Studio and pass the focus to SMath. When this occurs, you must attempt to utilize the plug‐in you have created for the purpose of debugging it. In this case, we type in the following:

As soon as the “=” is entered, if a breakpoint was set, control and screen focus will return to Visual Studio where you can step through the code, watch variable values, and other debugging tasks.

See endnote 5 for some useful links on how to debug your applications within Visual Studio.

33. To stop debugging, click on Debug ⇒ Stop Debugging as shown below. When you do this, the instance of SMath in which you tested your plug-in will close.

34. Finally, when your plug-in is finished and bug free, you are ready to release it. This essentially involves repeating steps 25 to 28 outlined above, with Relase configuration. The main difference is that the CombinFunction.pdb file does not need to be copied into the “SMath Studio\Plugins” folder.

To know how to relase your plug-in to the community, please visit the following link: http://en.smath.info/forum/yaf_postst2399_Extensions-Manager.aspx

Probably you have noticed that the Visual Studio IntelliSense provides hints about methods and properties available for the various namespaces; you can find a list of the featues available within the SMath Studio APIs in his Extensions Manager; go to Tools ⇒ Plugins... ⇒ Handbooks then choose Online gallery and search the keyword core.